Frontend Storybook: Kattava opas komponenttien kehitysympäristöihin

Jatkuvasti kehittyvässä frontend-kehityksen maailmassa vankkojen ja ylläpidettävien käyttöliittymien (UI) rakentaminen on ensisijaisen tärkeää. Storybook on noussut johtavaksi työkaluksi tähän haasteeseen vastaamisessa tarjoten tehokkaan ympäristön UI-komponenttien kehittämiseen eristyksissä. Tämä opas tarjoaa kattavan katsauksen Storybookiin, käsitellen sen ydinajatuksia, etuja, käytännön toteutusta ja edistyneitä tekniikoita frontend-kehitystyönkulun parantamiseksi.

Mitä on Storybook?

Storybook on avoimen lähdekoodin työkalu UI-komponenttien kehittämiseen eristyksissä. Se tarjoaa erillisen ympäristön, jossa voit rakentaa, testata ja dokumentoida komponentteja riippumatta pääsovelluksestasi. Tämä eristys mahdollistaa keskittymisen komponentin toiminnallisuuteen ja ulkonäköön ilman monimutkaisen sovelluslogiikan tai riippuvuuksien asettamia esteitä.

Ajattele Storybookia elävänä tyylioppaana tai komponenttikirjastona, joka esittelee visuaalisesti UI-komponenttejasi. Se antaa kehittäjille, suunnittelijoille ja sidosryhmille mahdollisuuden selata ja vuorovaikuttaa komponenttien kanssa johdonmukaisesti ja järjestelmällisesti, mikä edistää yhteistyötä ja varmistaa yhteisymmärryksen käyttöliittymästä.

Miksi käyttää Storybookia? Edut

Storybookin integrointi frontend-kehitystyönkulkuun tarjoaa lukuisia etuja:

• Parempi komponenttien uudelleenkäytettävyys: Komponenttien kehittäminen eristyksissä kannustaa modulaariseen lähestymistapaan, mikä tekee niistä helpommin uudelleenkäytettäviä sovelluksesi eri osissa tai jopa useissa eri projekteissa.
• Nopeampi kehitys: Storybook nopeuttaa kehitystä antamalla sinun keskittyä yksittäisiin komponentteihin ilman koko sovelluksen ajamisen aiheuttamaa yleiskustannusta. Voit nopeasti iteroida komponenttien suunnittelua ja toiminnallisuutta.
• Yksinkertaistettu testaus: Storybook helpottaa komponenttien testaamista eri tiloissa ja skenaarioissa. Voit luoda "storyja", jotka edustavat eri käyttötapauksia ja varmistaa visuaalisesti, että komponentti toimii odotetusti.
• Kattava dokumentaatio: Storybook toimii elävänä dokumentaationa UI-komponenteillesi. Se luo automaattisesti dokumentaation komponenttikoodisi ja storyjesi perusteella, mikä helpottaa muiden ymmärtämistä, miten niitä käytetään ja muokataan.
• Parempi yhteistyö: Storybook tarjoaa keskitetyn paikan kehittäjille, suunnittelijoille ja sidosryhmille tehdä yhteistyötä UI-komponenttien parissa. Se mahdollistaa visuaaliset katselmukset, palautteen antamisen ja yhteisymmärryksen UI-kirjastosta.
• Ongelmien varhainen havaitseminen: Kehittämällä komponentteja eristyksissä voit tunnistaa ja ratkaista ongelmia varhaisessa vaiheessa kehityssykliä, ennen kuin niistä tulee monimutkaisempia ja kalliimpia korjata.
• Design-järjestelmän johdonmukaisuus: Storybook edistää design-järjestelmän johdonmukaisuutta tarjoamalla visuaalisen referenssin kaikille UI-komponenteille. Se varmistaa, että komponentit noudattavat suunnitteluohjeita ja säilyttävät yhtenäisen ilmeen koko sovelluksessa.

Storybookin käyttöönotto

Storybookin asentaminen on suoraviivaista, ja se integroituu saumattomasti suosittuihin frontend-kehyksiin, kuten React, Vue ja Angular.

Asennus

Helpoin tapa asentaa Storybook on käyttää komentoriviliittymää (CLI). Avaa terminaali ja siirry projektihakemistoosi. Suorita sitten seuraava komento:

            npx storybook init
            

              
                Copy
              
            
          

Tämä komento tunnistaa automaattisesti projektisi kehyksen ja asentaa tarvittavat riippuvuudet. Se luo myös projektiisi .storybook-hakemiston, joka sisältää Storybookin konfiguraatiotiedostot.

Ensimmäisen storyn luominen

"Story" Storybookissa edustaa komponentin tiettyä tilaa tai käyttötapausta. Luodaksesi storyn, luot tyypillisesti uuden tiedoston projektisi src/stories-hakemistoon (tai vastaavaan paikkaan projektirakenteestasi riippuen). Tiedoston tulee olla .stories.js- tai .stories.jsx-päätteinen (Reactille) tai vastaava Vuelle tai Angularille.

Tässä on esimerkki yksinkertaisesta storysta React-painikekomponentille:

            // src/stories/Button.stories.jsx
import React from 'react';

import { Button } from './Button'; // Olettaen, että Button-komponenttisi on Button.jsx-tiedostossa

export default {
  title: 'Esimerkki/Painike',
  component: Button,
};

const Template = (args) => <Button {...args} />;

export const Primary = Template.bind({});
Primary.args = {
  primary: true,
  label: 'Ensisijainen painike',
};

export const Secondary = Template.bind({});
Secondary.args = {
  label: 'Toissijainen painike',
};

export const Large = Template.bind({});
Large.args = {
  size: 'large',
  label: 'Suuri painike',
};

export const Small = Template.bind({});
Small.args = {
  size: 'small',
  label: 'Pieni painike',
};

            

              
                Copy
              
            
          

Tässä esimerkissä määrittelemme Button-nimisen komponentin ja luomme neljä storya: Primary, Secondary, Large ja Small. Jokainen story edustaa painikekomponentin eri variaatiota eri propseilla.

Storybookin ajaminen

Ajaaksesi Storybookin, käytä seuraavaa komentoa:

            npm run storybook
            

              
                Copy
              
            
          

Tämä käynnistää paikallisen kehityspalvelimen ja avaa Storybookin selaimeesi. Sinun pitäisi nähdä storysi Storybookin käyttöliittymässä.

Storybookin ydinajatukset

Jotta voit käyttää Storybookia tehokkaasti, on tärkeää ymmärtää sen ydinajatukset:

• Komponentit: Käyttöliittymäsi perusrakennuspalikat. Storybook on suunniteltu esittelemään ja kehittämään yksittäisiä komponentteja eristyksissä.
• Storyt: Edustavat komponentin tiettyjä tiloja tai käyttötapauksia. Ne määrittelevät komponentille välitettävät propsit ja datan, mikä mahdollistaa erilaisten skenaarioiden visualisoinnin ja testaamisen.
• Lisäosat (Addons): Laajentavat Storybookin toiminnallisuutta erilaisilla ominaisuuksilla, kuten teemoituksella, saavutettavuustestauksella ja dokumentaation luomisella.
• Dekoraattorit (Decorators): Käärivät komponentteja lisätoiminnallisuudella, kuten tarjoamalla kontekstia tai tyylitystä.
• Args: (Aiemmin tunnettu nimellä knobs) Mahdollistavat komponentin propsien interaktiivisen muokkaamisen Storybookin käyttöliittymässä. Tämä on hyödyllistä erilaisten variaatioiden ja konfiguraatioiden tutkimisessa.
• Kontrollit (Controls): Käyttöliittymäelementit Argsien muokkaamiseen, mikä tekee komponentin ominaisuuksien säätämisestä selaimessa helppoa.

Edistyneet Storybook-tekniikat

Kun olet omaksunut Storybookin perusteet, voit tutustua edistyneisiin tekniikoihin työnkulun parantamiseksi entisestään:

Lisäosien käyttö

Storybook tarjoaa laajan valikoiman lisäosia, jotka voivat laajentaa sen toiminnallisuutta. Joitakin suosittuja lisäosia ovat:

• @storybook/addon-knobs: (Vanhentunut Args/Controls-ominaisuuden myötä) Mahdollistaa komponentin propsien interaktiivisen muokkaamisen Storybookin käyttöliittymässä.
• @storybook/addon-actions: Näyttää tapahtumankäsittelijät, jotka laukeavat komponentin vuorovaikutuksista.
• @storybook/addon-links: Luo linkkejä storyjen välille, mikä mahdollistaa navigoinnin eri komponenttitilojen välillä.
• @storybook/addon-docs: Luo dokumentaation komponenteillesi koodisi ja storyjesi perusteella.
• @storybook/addon-a11y: Suorittaa saavutettavuustarkistuksia komponenteillesi varmistaakseen, että ne ovat käytettävissä myös vammaisille henkilöille.
• @storybook/addon-viewport: Mahdollistaa komponenttien tarkastelun eri näyttöko'oissa ja laitteilla.
• @storybook/addon-backgrounds: Antaa sinun vaihtaa storyjesi taustaväriä komponentin kontrastin testaamiseksi.
• @storybook/addon-themes: Mahdollistaa eri teemojen välillä vaihtamisen Storybookissasi.

Asentaaksesi lisäosan, käytä seuraavaa komentoa:

            npm install @storybook/addon-name --save-dev
            

              
                Copy
              
            
          

Lisää sitten lisäosa .storybook/main.js-tiedostoosi:

            module.exports = {
  stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
    '@storybook/addon-a11y',
  ],
  framework: '@storybook/react',
  core: {
    builder: '@storybook/builder-webpack5',
  },
  features: {
    interactionsDebugger: true,
  },
};

            

              
                Copy
              
            
          

Dekoraattoreiden käyttö

Dekoraattorit ovat funktioita, jotka käärivät komponenttisi lisätoiminnallisuudella. Niitä voidaan käyttää kontekstin, tyylityksen tai muiden globaalien konfiguraatioiden tarjoamiseen.

Tässä on esimerkki dekoraattorista, joka tarjoaa teemakontekstin komponenteillesi:

            // src/stories/decorators/ThemeProvider.jsx
import React from 'react';
import { ThemeProvider } from 'styled-components';
import { theme } from './theme'; // Oma teemaobjektisi

export const ThemeDecorator = (Story) => (
  <ThemeProvider theme={theme}>
    <Story />
  </ThemeProvider>
);

            

              
                Copy
              
            
          

Käyttääksesi dekoraattoria, lisää se storysi konfiguraatioon:

            // src/stories/Button.stories.jsx
import React from 'react';
import { Button } from './Button';
import { ThemeDecorator } from './decorators/ThemeProvider';

export default {
  title: 'Esimerkki/Painike',
  component: Button,
  decorators: [ThemeDecorator],
};

            

              
                Copy
              
            
          

Automaattinen testaus Storybookilla

Storybook voidaan integroida erilaisiin testaustyökaluihin UI-komponenttiesi automaattista testausta varten. Joitakin suosittuja testauskehyksiä ovat:

• Jest: JavaScript-testauskehys, jota voidaan käyttää yksikkötestien kirjoittamiseen komponenteillesi.
• React Testing Library: Testauskirjasto, joka keskittyy komponenttien testaamiseen käyttäjän näkökulmasta.
• Cypress: End-to-end-testauskehys, jota voidaan käyttää koko sovelluksen, mukaan lukien UI-komponenttien, testaamiseen.
• Playwright: Cypressin kaltainen Playwright on tarkoitettu end-to-end-testaukseen eri selaimissa ja alustoilla.

Storybook-tiimi ylläpitää myös kirjastoa nimeltä @storybook/testing-react (tai vastaavaa Vuelle/Angularille), joka tarjoaa apuvälineitä komponenttiesi testaamiseen Storybookissa.

Storybookin julkaiseminen

Voit helposti julkaista Storybookisi ja jakaa sen tiimisi tai laajemman yhteisön kanssa. Saatavilla on useita vaihtoehtoja:

• Netlify: Suosittu alusta staattisten verkkosivustojen, mukaan lukien Storybookien, julkaisemiseen.
• GitHub Pages: GitHubin tarjoama ilmainen hosting-palvelu, jota voidaan käyttää Storybookin isännöintiin.
• Chromatic: Pilvipohjainen alusta, joka on suunniteltu erityisesti Storybookien isännöintiin ja hallintaan. Chromatic tarjoaa ominaisuuksia, kuten visuaalisen regressiotestauksen ja yhteistyötyökaluja.
• AWS S3: Voit isännöidä staattisia Storybook-tiedostojasi Amazon S3 -säiliössä (bucket).

Julkaistaksesi Storybookisi, sinun on tyypillisesti rakennettava staattinen versio siitä seuraavalla komennolla:

            npm run build-storybook
            

              
                Copy
              
            
          

Tämä luo storybook-static-hakemiston (tai vastaavan), joka sisältää staattiset tiedostot, jotka voidaan julkaista valitsemallasi hosting-alustalla.

Parhaat käytännöt Storybookin käyttöön

Maksimoidaksesi Storybookin hyödyt, noudata näitä parhaita käytäntöjä:

• Pidä komponentit pieninä ja kohdennettuina: Suunnittele komponenttisi mahdollisimman pieniksi ja tarkkarajaisiksi. Tämä tekee niistä helpompia testata, uudelleenkäyttää ja dokumentoida.
• Kirjoita kattavia storyja: Luo storyja, jotka kattavat kaikki komponenttiesi eri tilat ja käyttötapaukset. Tämä varmistaa, että komponenttisi on testattu ja dokumentoitu perusteellisesti.
• Käytä lisäosia viisaasti: Valitse lisäosia, jotka ovat olennaisia projektisi tarpeisiin, ja vältä liian monien lisäosien lisäämistä, sillä se voi vaikuttaa suorituskykyyn.
• Dokumentoi komponenttisi huolellisesti: Käytä @storybook/addon-docs-lisäosaa luodaksesi dokumentaation komponenteillesi. Tämä helpottaa muiden ymmärtämistä, miten niitä käytetään ja muokataan.
• Integroi Storybook osaksi kehitystyönkulkuasi: Tee Storybookista olennainen osa kehitystyönkulkuasi. Käytä sitä UI-komponenttien kehittämiseen, testaamiseen ja dokumentointiin projektin alusta alkaen.
• Luo selkeä komponenttikirjaston rakenne: Järjestä komponenttikirjastosi loogisesti ja johdonmukaisesti. Tämä helpottaa muiden löytää ja uudelleenkäyttää komponentteja.
• Ylläpidä Storybookia säännöllisesti: Pidä Storybook ajan tasalla UI-komponenttiesi uusimpien muutosten kanssa. Tämä varmistaa, että dokumentaatiosi on tarkka ja että komponenttisi testataan aina uusinta koodia vasten.
• Käytä versionhallintaa: Tallenna Storybook-konfiguraatiosi ja storysi versionhallintaan (esim. Git) muutosten seuraamiseksi ja yhteistyön tekemiseksi muiden kanssa.

Storybook eri kehyksissä

Vaikka ydinajatukset pysyvät samanlaisina, Storybookin toteutuksen yksityiskohdat vaihtelevat hieman riippuen käyttämästäsi frontend-kehyksestä.

Storybook Reactille

React on yksi suosituimmista kehyksistä Storybookin käyttöön. Virallinen Storybook-dokumentaatio tarjoaa erinomaisia resursseja ja esimerkkejä React-kehittäjille.

Storybook Vuelle

Storybook integroituu saumattomasti myös Vue.js:n kanssa. Vue-komponentit voidaan helposti lisätä Storybookiin samankaltaisella lähestymistavalla kuin Reactissa.

Storybook Angularille

Angular-kehittäjät voivat hyödyntää Storybookia luodakseen visuaalisen komponenttikirjaston Angular-sovelluksilleen. Angular CLI -integraatio tekee asennusprosessista suoraviivaisen.

Globaalit näkökulmat ja esimerkit

Kun käytät Storybookia globaaleissa projekteissa, on tärkeää ottaa huomioon UI-komponenttiesi lokalisointi- ja kansainvälistämisnäkökohdat. Esimerkiksi:

• Tekstin suunta (RTL/LTR): Varmista, että komponenttisi tukevat sekä vasemmalta oikealle (LTR) että oikealta vasemmalle (RTL) -tekstisuuntia. Voit käyttää Storybookia luodaksesi storyja, jotka esittelevät komponentteja molemmissa suunnissa. Harkitse kirjastojen, kuten `styled-components` ja `rtlcss`-laajennuksen, käyttöä tyylimuunnosten automaattiseen käsittelyyn.
• Päivämäärä- ja aikamuodot: Käytä sopivia päivämäärä- ja aikamuotoja käyttäjän lokaalin perusteella. Voit käyttää kirjastoja, kuten `moment.js` tai `date-fns`, muotoillaksesi päivämääriä ja aikoja oikein. Luo storyja, jotka esittelevät komponentteja eri päivämäärä- ja aikamuodoilla.
• Valuuttamuodot: Näytä valuutta-arvot oikeassa muodossa käyttäjän lokaalin mukaan. Voit käyttää kirjastoja, kuten `numeral.js` tai `Intl.NumberFormat`, muotoillaksesi valuutta-arvoja. Luo storyja, jotka esittelevät komponentteja eri valuuttamuodoilla ja -symboleilla.
• Käännökset: Käytä kansainvälistämis- (i18n) kirjastoja kääntääksesi UI-komponenttisi eri kielille. Storybookia voidaan käyttää visualisoimaan komponentteja eri käännöksillä. Kirjastoja, kuten `i18next`, käytetään yleisesti.
• Saavutettavuus: Noudata verkkosaavutettavuuden ohjeita varmistaaksesi, että UI-komponenttisi ovat käytettävissä myös vammaisille henkilöille, heidän sijainnistaan riippumatta.

Esimerkki: Kuvittele globaalisti käytetty lomakekomponentti. Storybook-storyssa voisit esitellä:

• Lomakkeen, jonka kenttien nimet ja ohjeet on käännetty espanjaksi.
• Saman lomakkeen näytettynä RTL-asettelulla arabiankielisille käyttäjille.
• Lomakkeen, jossa päivämääräkenttä näytetään muodossa KK/PP/VVVV Yhdysvaltoja varten ja PP/KK/VVVV Eurooppaa varten.

Yhteenveto

Storybook on tehokas työkalu, joka voi merkittävästi parantaa frontend-kehitystyönkulkuasi. Tarjoamalla eristetyn ympäristön UI-komponenttien kehittämiseen se edistää uudelleenkäytettävyyttä, nopeuttaa kehitystä, yksinkertaistaa testausta ja helpottaa yhteistyötä. Olitpa rakentamassa pientä verkkosivustoa tai laajamittaista sovellusta, Storybook voi auttaa sinua luomaan vakaita, ylläpidettäviä ja johdonmukaisia käyttöliittymiä.

Omaksumalla tässä oppaassa esitellyt käsitteet ja tekniikat voit hyödyntää Storybookin koko potentiaalin ja rakentaa poikkeuksellisia käyttäjäkokemuksia globaalille yleisöllesi.